<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Character Generators (char_, lit)</title>
<link rel="stylesheet" href="../../../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../../../index.html" title="Spirit 2.59">
<link rel="up" href="../char.html" title="Char Generators">
<link rel="prev" href="../char.html" title="Char Generators">
<link rel="next" href="char_class.html" title="Character Classification Generators (alnum, digit, etc.)">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../char.html"><img src="../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../char.html"><img src="../../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="char_class.html"><img src="../../../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h5 class="title">
<a name="spirit.karma.reference.char.char_generator"></a><a class="link" href="char_generator.html" title="Character Generators (char_, lit)">Character
          Generators (<code class="computeroutput"><span class="identifier">char_</span></code>, <code class="computeroutput"><span class="identifier">lit</span></code>)</a>
</h5></div></div></div>
<h6>
<a name="spirit.karma.reference.char.char_generator.h0"></a>
            <span class="phrase"><a name="spirit.karma.reference.char.char_generator.description"></a></span><a class="link" href="char_generator.html#spirit.karma.reference.char.char_generator.description">Description</a>
          </h6>
<p>
            The character generators described in this section are:
          </p>
<p>
            The <code class="computeroutput"><span class="identifier">char_</span></code> generator emits
            single characters. The <code class="computeroutput"><span class="identifier">char_</span></code>
            generator has an associated <a class="link" href="../basics.html#spirit.karma.reference.basics.character_encoding_namespace">Character
            Encoding Namespace</a>. This is needed when doing basic operations
            such as forcing lower or upper case and dealing with character ranges.
          </p>
<p>
            There are various forms of <code class="computeroutput"><span class="identifier">char_</span></code>.
          </p>
<h6>
<a name="spirit.karma.reference.char.char_generator.h1"></a>
            <span class="phrase"><a name="spirit.karma.reference.char.char_generator.char_"></a></span><a class="link" href="char_generator.html#spirit.karma.reference.char.char_generator.char_">char_</a>
          </h6>
<p>
            The no argument form of <code class="computeroutput"><span class="identifier">char_</span></code>
            emits any character in the associated <a class="link" href="../basics.html#spirit.karma.reference.basics.character_encoding_namespace">Character
            Encoding Namespace</a>.
          </p>
<pre class="programlisting"><span class="identifier">char_</span>               <span class="comment">// emits any character as supplied by the attribute</span>
</pre>
<h6>
<a name="spirit.karma.reference.char.char_generator.h2"></a>
            <span class="phrase"><a name="spirit.karma.reference.char.char_generator.char__ch_"></a></span><a class="link" href="char_generator.html#spirit.karma.reference.char.char_generator.char__ch_">char_(ch)</a>
          </h6>
<p>
            The single argument form of <code class="computeroutput"><span class="identifier">char_</span></code>
            (with a character argument) emits the supplied character.
          </p>
<pre class="programlisting"><span class="identifier">char_</span><span class="special">(</span><span class="char">'x'</span><span class="special">)</span>          <span class="comment">// emits 'x'</span>
<span class="identifier">char_</span><span class="special">(</span><span class="identifier">L</span><span class="char">'x'</span><span class="special">)</span>         <span class="comment">// emits L'x'</span>
<span class="identifier">char_</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span>            <span class="comment">// emits x (a char)</span>
</pre>
<h6>
<a name="spirit.karma.reference.char.char_generator.h3"></a>
            <span class="phrase"><a name="spirit.karma.reference.char.char_generator.char__first__last_"></a></span><a class="link" href="char_generator.html#spirit.karma.reference.char.char_generator.char__first__last_">char_(first,
            last)</a>
          </h6>
<p>
            <code class="computeroutput"><span class="identifier">char_</span></code> with two arguments,
            emits any character from a range of characters as supplied by the attribute.
          </p>
<pre class="programlisting"><span class="identifier">char_</span><span class="special">(</span><span class="char">'a'</span><span class="special">,</span><span class="char">'z'</span><span class="special">)</span>      <span class="comment">// alphabetic characters</span>
<span class="identifier">char_</span><span class="special">(</span><span class="identifier">L</span><span class="char">'0'</span><span class="special">,</span><span class="identifier">L</span><span class="char">'9'</span><span class="special">)</span>    <span class="comment">// digits</span>
</pre>
<p>
            A range of characters is created from a low-high character pair. Such
            a generator emits a single character that is in the range, including
            both endpoints. Note, the first character must be <span class="emphasis"><em>before</em></span>
            the second, according to the underlying <a class="link" href="../basics.html#spirit.karma.reference.basics.character_encoding_namespace">Character
            Encoding Namespace</a>.
          </p>
<p>
            Character mapping is inherently platform dependent. It is not guaranteed
            in the standard for example that <code class="computeroutput"><span class="char">'A'</span>
            <span class="special">&lt;</span> <span class="char">'Z'</span></code>,
            that is why in Spirit2, we purposely attach a specific <a class="link" href="../basics.html#spirit.karma.reference.basics.character_encoding_namespace">Character
            Encoding Namespace</a> (such as ASCII, ISO-8859-1) to the <code class="computeroutput"><span class="identifier">char_</span></code> generator to eliminate such ambiguities.
          </p>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top">
<p>
              <span class="bold"><strong>Sparse bit vectors</strong></span>
            </p>
<p>
              To accommodate 16/32 and 64 bit characters, the char-set statically
              switches from a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">bitset</span></code>
              implementation when the character type is not greater than 8 bits,
              to a sparse bit/boolean set which uses a sorted vector of disjoint
              ranges (<code class="computeroutput"><span class="identifier">range_run</span></code>).
              The set is constructed from ranges such that adjacent or overlapping
              ranges are coalesced.
            </p>
<p>
              <code class="computeroutput"><span class="identifier">range_runs</span></code> are very
              space-economical in situations where there are lots of ranges and a
              few individual disjoint values. Searching is O(log n) where n is the
              number of ranges.
            </p>
</td></tr>
</table></div>
<h6>
<a name="spirit.karma.reference.char.char_generator.h4"></a>
            <span class="phrase"><a name="spirit.karma.reference.char.char_generator.char__def_"></a></span><a class="link" href="char_generator.html#spirit.karma.reference.char.char_generator.char__def_">char_(def)</a>
          </h6>
<p>
            Lastly, when given a string (a plain C string, a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">basic_string</span></code>,
            etc.), the string is regarded as a char-set definition string following
            a syntax that resembles posix style regular expression character sets
            (except that double quotes delimit the set elements instead of square
            brackets and there is no special negation ^ character). Examples:
          </p>
<pre class="programlisting"><span class="identifier">char_</span><span class="special">(</span><span class="string">"a-zA-Z"</span><span class="special">)</span>     <span class="comment">// alphabetic characters</span>
<span class="identifier">char_</span><span class="special">(</span><span class="string">"0-9a-fA-F"</span><span class="special">)</span>  <span class="comment">// hexadecimal characters</span>
<span class="identifier">char_</span><span class="special">(</span><span class="string">"actgACTG"</span><span class="special">)</span>   <span class="comment">// DNA identifiers</span>
<span class="identifier">char_</span><span class="special">(</span><span class="string">"\x7f\x7e"</span><span class="special">)</span>   <span class="comment">// Hexadecimal 0x7F and 0x7E</span>
</pre>
<p>
            These generators emit any character from a range of characters as supplied
            by the attribute.
          </p>
<h6>
<a name="spirit.karma.reference.char.char_generator.h5"></a>
            <span class="phrase"><a name="spirit.karma.reference.char.char_generator.lit_ch_"></a></span><a class="link" href="char_generator.html#spirit.karma.reference.char.char_generator.lit_ch_">lit(ch)</a>
          </h6>
<p>
            <code class="computeroutput"><span class="identifier">lit</span></code>, when passed a single
            character, behaves like the single argument <code class="computeroutput"><span class="identifier">char_</span></code>
            except that <code class="computeroutput"><span class="identifier">lit</span></code> does
            not consume an attribute. A plain <code class="computeroutput"><span class="keyword">char</span></code>
            or <code class="computeroutput"><span class="keyword">wchar_t</span></code> is equivalent
            to a <code class="computeroutput"><span class="identifier">lit</span></code>.
          </p>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
              <code class="computeroutput"><span class="identifier">lit</span></code> is reused by the
              <a class="link" href="../string.html" title="String Generators">String Generators</a>,
              the char generators, and the Numeric Generators (see <a class="link" href="../numeric/signed_int.html" title="Signed Integer Number Generators (int_, etc.)">signed
              integer</a>, <a class="link" href="../numeric/unsigned_int.html" title="Unsigned Integer Number Generators (uint_, etc.)">unsigned
              integer</a>, and <a class="link" href="../numeric/real_number.html" title="Real Number Generators (float_, double_, etc.)">real
              number</a> generators). In general, a char generator is created
              when you pass in a character, a string generator is created when you
              pass in a string, and a numeric generator is created when you use a
              numeric literal. The exception is when you pass a single element literal
              string, e.g. <code class="computeroutput"><span class="identifier">lit</span><span class="special">(</span><span class="string">"x"</span><span class="special">)</span></code>.
              In this case, we optimize this to create a char generator instead of
              a string generator.
            </p></td></tr>
</table></div>
<p>
            Examples:
          </p>
<pre class="programlisting"><span class="char">'x'</span>
<span class="identifier">lit</span><span class="special">(</span><span class="char">'x'</span><span class="special">)</span>
<span class="identifier">lit</span><span class="special">(</span><span class="identifier">L</span><span class="char">'x'</span><span class="special">)</span>
<span class="identifier">lit</span><span class="special">(</span><span class="identifier">c</span><span class="special">)</span>      <span class="comment">// c is a char</span>
</pre>
<h6>
<a name="spirit.karma.reference.char.char_generator.h6"></a>
            <span class="phrase"><a name="spirit.karma.reference.char.char_generator.header"></a></span><a class="link" href="char_generator.html#spirit.karma.reference.char.char_generator.header">Header</a>
          </h6>
<pre class="programlisting"><span class="comment">// forwards to &lt;boost/spirit/home/karma/char/char.hpp&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">karma_char_</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
</pre>
<p>
            Also, see <a class="link" href="../../../structure/include.html" title="Include">Include Structure</a>.
          </p>
<h6>
<a name="spirit.karma.reference.char.char_generator.h7"></a>
            <span class="phrase"><a name="spirit.karma.reference.char.char_generator.namespace"></a></span><a class="link" href="char_generator.html#spirit.karma.reference.char.char_generator.namespace">Namespace</a>
          </h6>
<div class="informaltable"><table class="table">
<colgroup><col></colgroup>
<thead><tr><th>
                    <p>
                      Name
                    </p>
                  </th></tr></thead>
<tbody>
<tr><td>
                    <p>
                      <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">lit</span> <span class="comment">// alias:
                      boost::spirit::karma::lit</span></code>
                    </p>
                  </td></tr>
<tr><td>
                    <p>
                      <code class="computeroutput"><span class="identifier">ns</span><span class="special">::</span><span class="identifier">char_</span></code>
                    </p>
                  </td></tr>
</tbody>
</table></div>
<p>
            In the table above, <code class="computeroutput"><span class="identifier">ns</span></code>
            represents a <a class="link" href="../basics.html#spirit.karma.reference.basics.character_encoding_namespace">Character
            Encoding Namespace</a>.
          </p>
<h6>
<a name="spirit.karma.reference.char.char_generator.h8"></a>
            <span class="phrase"><a name="spirit.karma.reference.char.char_generator.model_of"></a></span><a class="link" href="char_generator.html#spirit.karma.reference.char.char_generator.model_of">Model of</a>
          </h6>
<div class="blockquote"><blockquote class="blockquote"><p>
              <a class="link" href="../generator_concepts/primitivegenerator.html" title="PrimitiveGenerator"><code class="computeroutput"><span class="identifier">PrimitiveGenerator</span></code></a>
            </p></blockquote></div>
<div class="variablelist">
<p class="title"><b>Notation</b></p>
<dl class="variablelist">
<dt><span class="term"><code class="computeroutput"><span class="identifier">ch</span></code>, <code class="computeroutput"><span class="identifier">ch1</span></code>, <code class="computeroutput"><span class="identifier">ch2</span></code></span></dt>
<dd><p>
                  Character-class specific character (See Character Class Types),
                  or a <a class="link" href="../basics.html#spirit.karma.reference.basics.lazy_argument">Lazy
                  Argument</a> that evaluates to a character-class specific character
                  value
                </p></dd>
<dt><span class="term"><code class="computeroutput"><span class="identifier">cs</span></code></span></dt>
<dd><p>
                  Character-set specifier string (See Character Class Types), or
                  a <a class="link" href="../basics.html#spirit.karma.reference.basics.lazy_argument">Lazy
                  Argument</a> that evaluates to a character-set specifier string,
                  or a pointer/reference to a null-terminated array of characters.
                  This string specifies a char-set definition string following a
                  syntax that resembles posix style regular expression character
                  sets (except the square brackets and the negation <code class="computeroutput"><span class="special">^</span></code> character).
                </p></dd>
<dt><span class="term"><code class="computeroutput"><span class="identifier">ns</span></code></span></dt>
<dd><p>
                  A <a class="link" href="../basics.html#spirit.karma.reference.basics.character_encoding_namespace">Character
                  Encoding Namespace</a>.
                </p></dd>
<dt><span class="term"><code class="computeroutput"><span class="identifier">cg</span></code></span></dt>
<dd><p>
                  A char generator, a char range generator, or a char set generator.
                </p></dd>
</dl>
</div>
<h6>
<a name="spirit.karma.reference.char.char_generator.h9"></a>
            <span class="phrase"><a name="spirit.karma.reference.char.char_generator.expression_semantics"></a></span><a class="link" href="char_generator.html#spirit.karma.reference.char.char_generator.expression_semantics">Expression
            Semantics</a>
          </h6>
<p>
            Semantics of an expression is defined only where it differs from, or
            is not defined in <a class="link" href="../generator_concepts/primitivegenerator.html" title="PrimitiveGenerator"><code class="computeroutput"><span class="identifier">PrimitiveGenerator</span></code></a>.
          </p>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                    <p>
                      Expression
                    </p>
                  </th>
<th>
                    <p>
                      Description
                    </p>
                  </th>
</tr></thead>
<tbody>
<tr>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">ch</span></code>
                    </p>
                  </td>
<td>
                    <p>
                      Generate the character literal <code class="computeroutput"><span class="identifier">ch</span></code>.
                      This generator never fails (unless the underlying output stream
                      reports an error).
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">lit</span><span class="special">(</span><span class="identifier">ch</span><span class="special">)</span></code>
                    </p>
                  </td>
<td>
                    <p>
                      Generate the character literal <code class="computeroutput"><span class="identifier">ch</span></code>.
                      This generator never fails (unless the underlying output stream
                      reports an error).
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">ns</span><span class="special">::</span><span class="identifier">char_</span></code>
                    </p>
                  </td>
<td>
                    <p>
                      Generate the character provided by a mandatory attribute interpreted
                      in the character set defined by <code class="computeroutput"><span class="identifier">ns</span></code>.
                      This generator never fails (unless the underlying output stream
                      reports an error).
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">ns</span><span class="special">::</span><span class="identifier">char_</span><span class="special">(</span><span class="identifier">ch</span><span class="special">)</span></code>
                    </p>
                  </td>
<td>
                    <p>
                      Generate the character <code class="computeroutput"><span class="identifier">ch</span></code>
                      as provided by the immediate literal value the generator is
                      initialized from. If this generator has an associated attribute
                      it succeeds only as long as the attribute is equal to the immediate
                      literal (unless the underlying output stream reports an error).
                      Otherwise this generator fails and does not generate any output.
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">ns</span><span class="special">::</span><span class="identifier">char_</span><span class="special">(</span><span class="string">"c"</span><span class="special">)</span></code>
                    </p>
                  </td>
<td>
                    <p>
                      Generate the character <code class="computeroutput"><span class="identifier">c</span></code>
                      as provided by the immediate literal value the generator is
                      initialized from. If this generator has an associated attribute
                      it succeeds only as long as the attribute is equal to the immediate
                      literal (unless the underlying output stream reports an error).
                      Otherwise this generator fails and does not generate any output.
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">ns</span><span class="special">::</span><span class="identifier">char_</span><span class="special">(</span><span class="identifier">ch1</span><span class="special">,</span>
                      <span class="identifier">ch2</span><span class="special">)</span></code>
                    </p>
                  </td>
<td>
                    <p>
                      Generate the character provided by a mandatory attribute interpreted
                      in the character set defined by <code class="computeroutput"><span class="identifier">ns</span></code>.
                      The generator succeeds as long as the attribute belongs to
                      the character range <code class="computeroutput"><span class="special">[</span><span class="identifier">ch1</span><span class="special">,</span>
                      <span class="identifier">ch2</span><span class="special">]</span></code>
                      (unless the underlying output stream reports an error). Otherwise
                      this generator fails and does not generate any output.
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">ns</span><span class="special">::</span><span class="identifier">char_</span><span class="special">(</span><span class="identifier">cs</span><span class="special">)</span></code>
                    </p>
                  </td>
<td>
                    <p>
                      Generate the character provided by a mandatory attribute interpreted
                      in the character set defined by <code class="computeroutput"><span class="identifier">ns</span></code>.
                      The generator succeeds as long as the attribute belongs to
                      the character set <code class="computeroutput"><span class="identifier">cs</span></code>
                      (unless the underlying output stream reports an error). Otherwise
                      this generator fails and does not generate any output.
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p>
                      <code class="computeroutput"><span class="special">~</span><span class="identifier">cg</span></code>
                    </p>
                  </td>
<td>
                    <p>
                      Negate <code class="computeroutput"><span class="identifier">cg</span></code>.
                      The result is a negated char generator that inverts the test
                      condition of the character generator it is attached to.
                    </p>
                  </td>
</tr>
</tbody>
</table></div>
<p>
            A character <code class="computeroutput"><span class="identifier">ch</span></code> is assumed
            to belong to the character range defined by <code class="computeroutput"><span class="identifier">ns</span><span class="special">::</span><span class="identifier">char_</span><span class="special">(</span><span class="identifier">ch1</span><span class="special">,</span> <span class="identifier">ch2</span><span class="special">)</span></code> if its character value (binary representation)
            interpreted in the character set defined by <code class="computeroutput"><span class="identifier">ns</span></code>
            is not smaller than the character value of <code class="computeroutput"><span class="identifier">ch1</span></code>
            and not larger then the character value of <code class="computeroutput"><span class="identifier">ch2</span></code>
            (i.e. <code class="computeroutput"><span class="identifier">ch1</span> <span class="special">&lt;=</span>
            <span class="identifier">ch</span> <span class="special">&lt;=</span>
            <span class="identifier">ch2</span></code>).
          </p>
<p>
            The <code class="computeroutput"><span class="identifier">charset</span></code> parameter
            passed to <code class="computeroutput"><span class="identifier">ns</span><span class="special">::</span><span class="identifier">char_</span><span class="special">(</span><span class="identifier">charset</span><span class="special">)</span></code>
            must be a string containing more than one character. Every single character
            in this string is assumed to belong to the character set defined by this
            expression. An exception to this is the <code class="computeroutput"><span class="char">'-'</span></code>
            character which has a special meaning if it is not specified as the first
            and not the last character in <code class="computeroutput"><span class="identifier">charset</span></code>.
            If the <code class="computeroutput"><span class="char">'-'</span></code> is used in between
            to characters it is interpreted as spanning a character range. A character
            <code class="computeroutput"><span class="identifier">ch</span></code> is considered to belong
            to the defined character set <code class="computeroutput"><span class="identifier">charset</span></code>
            if it matches one of the characters as specified by the string parameter
            described above. For example
          </p>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                    <p>
                      Example
                    </p>
                  </th>
<th>
                    <p>
                      Description
                    </p>
                  </th>
</tr></thead>
<tbody>
<tr>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">char_</span><span class="special">(</span><span class="string">"abc"</span><span class="special">)</span></code>
                    </p>
                  </td>
<td>
                    <p>
                      'a', 'b', and 'c'
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">char_</span><span class="special">(</span><span class="string">"a-z"</span><span class="special">)</span></code>
                    </p>
                  </td>
<td>
                    <p>
                      all characters (and including) from 'a' to 'z'
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">char_</span><span class="special">(</span><span class="string">"a-zA-Z"</span><span class="special">)</span></code>
                    </p>
                  </td>
<td>
                    <p>
                      all characters (and including) from 'a' to 'z' and 'A' and
                      'Z'
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">char_</span><span class="special">(</span><span class="string">"-1-9"</span><span class="special">)</span></code>
                    </p>
                  </td>
<td>
                    <p>
                      '-' and all characters (and including) from '1' to '9'
                    </p>
                  </td>
</tr>
</tbody>
</table></div>
<h6>
<a name="spirit.karma.reference.char.char_generator.h10"></a>
            <span class="phrase"><a name="spirit.karma.reference.char.char_generator.attributes"></a></span><a class="link" href="char_generator.html#spirit.karma.reference.char.char_generator.attributes">Attributes</a>
          </h6>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
                    <p>
                      Expression
                    </p>
                  </th>
<th>
                    <p>
                      Attribute
                    </p>
                  </th>
</tr></thead>
<tbody>
<tr>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">ch</span></code>
                    </p>
                  </td>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">unused</span></code>
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">lit</span><span class="special">(</span><span class="identifier">ch</span><span class="special">)</span></code>
                    </p>
                  </td>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">unused</span></code>
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">ns</span><span class="special">::</span><span class="identifier">char_</span></code>
                    </p>
                  </td>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">Ch</span></code>, attribute
                      is mandatory (otherwise compilation will fail). <code class="computeroutput"><span class="identifier">Ch</span></code> is the character type
                      of the <a class="link" href="../basics.html#spirit.karma.reference.basics.character_encoding_namespace">Character
                      Encoding Namespace</a>, <code class="computeroutput"><span class="identifier">ns</span></code>.
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">ns</span><span class="special">::</span><span class="identifier">char_</span><span class="special">(</span><span class="identifier">ch</span><span class="special">)</span></code>
                    </p>
                  </td>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">Ch</span></code>, attribute
                      is optional, if it is supplied, the generator compares the
                      attribute with <code class="computeroutput"><span class="identifier">ch</span></code>
                      and succeeds only if both are equal, failing otherwise. <code class="computeroutput"><span class="identifier">Ch</span></code> is the character type
                      of the <a class="link" href="../basics.html#spirit.karma.reference.basics.character_encoding_namespace">Character
                      Encoding Namespace</a>, <code class="computeroutput"><span class="identifier">ns</span></code>.
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">ns</span><span class="special">::</span><span class="identifier">char_</span><span class="special">(</span><span class="string">"c"</span><span class="special">)</span></code>
                    </p>
                  </td>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">Ch</span></code>, attribute
                      is optional, if it is supplied, the generator compares the
                      attribute with <code class="computeroutput"><span class="identifier">c</span></code>
                      and succeeds only if both are equal, failing otherwise. <code class="computeroutput"><span class="identifier">Ch</span></code> is the character type
                      of the <a class="link" href="../basics.html#spirit.karma.reference.basics.character_encoding_namespace">Character
                      Encoding Namespace</a>, <code class="computeroutput"><span class="identifier">ns</span></code>.
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">ns</span><span class="special">::</span><span class="identifier">char_</span><span class="special">(</span><span class="identifier">ch1</span><span class="special">,</span>
                      <span class="identifier">ch2</span><span class="special">)</span></code>
                    </p>
                  </td>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">Ch</span></code>, attribute
                      is mandatory (otherwise compilation will fail), the generator
                      succeeds if the attribute belongs to the character range <code class="computeroutput"><span class="special">[</span><span class="identifier">ch1</span><span class="special">,</span> <span class="identifier">ch2</span><span class="special">]</span></code> interpreted in the character
                      set defined by <code class="computeroutput"><span class="identifier">ns</span></code>.
                      <code class="computeroutput"><span class="identifier">Ch</span></code> is the character
                      type of the <a class="link" href="../basics.html#spirit.karma.reference.basics.character_encoding_namespace">Character
                      Encoding Namespace</a>, <code class="computeroutput"><span class="identifier">ns</span></code>.
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">ns</span><span class="special">::</span><span class="identifier">char_</span><span class="special">(</span><span class="identifier">cs</span><span class="special">)</span></code>
                    </p>
                  </td>
<td>
                    <p>
                      <code class="computeroutput"><span class="identifier">Ch</span></code>, attribute
                      is mandatory (otherwise compilation will fail), the generator
                      succeeds if the attribute belongs to the character set <code class="computeroutput"><span class="identifier">cs</span></code>, interpreted in the character
                      set defined by <code class="computeroutput"><span class="identifier">ns</span></code>.
                      <code class="computeroutput"><span class="identifier">Ch</span></code> is the character
                      type of the <a class="link" href="../basics.html#spirit.karma.reference.basics.character_encoding_namespace">Character
                      Encoding Namespace</a>, <code class="computeroutput"><span class="identifier">ns</span></code>.
                    </p>
                  </td>
</tr>
<tr>
<td>
                    <p>
                      <code class="computeroutput"><span class="special">~</span><span class="identifier">cg</span></code>
                    </p>
                  </td>
<td>
                    <p>
                      Attribute of <code class="computeroutput"><span class="identifier">cg</span></code>
                    </p>
                  </td>
</tr>
</tbody>
</table></div>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
              In addition to their usual attribute of type <code class="computeroutput"><span class="identifier">Ch</span></code>
              all listed generators accept an instance of a <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">Ch</span><span class="special">&gt;</span></code> as well. If the <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span><span class="special">&lt;&gt;</span></code> is initialized (holds a value)
              the generators behave as if their attribute was an instance of <code class="computeroutput"><span class="identifier">Ch</span></code> and emit the value stored in the
              <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span><span class="special">&lt;&gt;</span></code>.
              Otherwise the generators will fail.
            </p></td></tr>
</table></div>
<h6>
<a name="spirit.karma.reference.char.char_generator.h11"></a>
            <span class="phrase"><a name="spirit.karma.reference.char.char_generator.complexity"></a></span><a class="link" href="char_generator.html#spirit.karma.reference.char.char_generator.complexity">Complexity</a>
          </h6>
<div class="blockquote"><blockquote class="blockquote"><p>
              O(1)
            </p></blockquote></div>
<p>
            The complexity of <code class="computeroutput"><span class="identifier">ch</span></code>,
            <code class="computeroutput"><span class="identifier">lit</span><span class="special">(</span><span class="identifier">ch</span><span class="special">)</span></code>,
            <code class="computeroutput"><span class="identifier">ns</span><span class="special">::</span><span class="identifier">char_</span></code>, <code class="computeroutput"><span class="identifier">ns</span><span class="special">::</span><span class="identifier">char_</span><span class="special">(</span><span class="identifier">ch</span><span class="special">)</span></code>, and <code class="computeroutput"><span class="identifier">ns</span><span class="special">::</span><span class="identifier">char_</span><span class="special">(</span><span class="string">"c"</span><span class="special">)</span></code> is constant as all generators emit exactly
            one character per invocation.
          </p>
<p>
            The character range generator (<code class="computeroutput"><span class="identifier">ns</span><span class="special">::</span><span class="identifier">char_</span><span class="special">(</span><span class="identifier">ch1</span><span class="special">,</span> <span class="identifier">ch2</span><span class="special">)</span></code>) additionally requires constant lookup
            time for the verification whether the attribute belongs to the character
            range.
          </p>
<p>
            The character set generator (<code class="computeroutput"><span class="identifier">ns</span><span class="special">::</span><span class="identifier">char_</span><span class="special">(</span><span class="identifier">cs</span><span class="special">)</span></code>) additionally requires O(log N) lookup
            time for the verification whether the attribute belongs to the character
            set, where N is the number of characters in the character set.
          </p>
<h6>
<a name="spirit.karma.reference.char.char_generator.h12"></a>
            <span class="phrase"><a name="spirit.karma.reference.char.char_generator.example"></a></span><a class="link" href="char_generator.html#spirit.karma.reference.char.char_generator.example">Example</a>
          </h6>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
              The test harness for the example(s) below is presented in the <a class="link" href="../basics.html#spirit.karma.reference.basics.examples">Basics Examples</a>
              section.
            </p></td></tr>
</table></div>
<p>
            Some includes:
          </p>
<p>
</p>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">karma</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">support_utree</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">phoenix</span><span class="special">/</span><span class="identifier">core</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">phoenix</span><span class="special">/</span><span class="keyword">operator</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">fusion</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">std_pair</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">proto</span><span class="special">/</span><span class="identifier">deep_copy</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">string</span><span class="special">&gt;</span>
</pre>
<p>
          </p>
<p>
            Some using declarations:
          </p>
<p>
</p>
<pre class="programlisting"><span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">karma</span><span class="special">::</span><span class="identifier">lit</span><span class="special">;</span>
<span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">ascii</span><span class="special">::</span><span class="identifier">char_</span><span class="special">;</span>
</pre>
<p>
          </p>
<p>
            Basic usage of <code class="computeroutput"><span class="identifier">char_</span></code>
            generators:
          </p>
<p>
</p>
<pre class="programlisting"><span class="identifier">test_generator</span><span class="special">(</span><span class="string">"A"</span><span class="special">,</span> <span class="char">'A'</span><span class="special">);</span>
<span class="identifier">test_generator</span><span class="special">(</span><span class="string">"A"</span><span class="special">,</span> <span class="identifier">lit</span><span class="special">(</span><span class="char">'A'</span><span class="special">));</span>

<span class="identifier">test_generator_attr</span><span class="special">(</span><span class="string">"a"</span><span class="special">,</span> <span class="identifier">char_</span><span class="special">,</span> <span class="char">'a'</span><span class="special">);</span>
<span class="identifier">test_generator</span><span class="special">(</span><span class="string">"A"</span><span class="special">,</span> <span class="identifier">char_</span><span class="special">(</span><span class="char">'A'</span><span class="special">));</span>
<span class="identifier">test_generator_attr</span><span class="special">(</span><span class="string">"A"</span><span class="special">,</span> <span class="identifier">char_</span><span class="special">(</span><span class="char">'A'</span><span class="special">),</span> <span class="char">'A'</span><span class="special">);</span>
<span class="identifier">test_generator_attr</span><span class="special">(</span><span class="string">""</span><span class="special">,</span> <span class="identifier">char_</span><span class="special">(</span><span class="char">'A'</span><span class="special">),</span> <span class="char">'B'</span><span class="special">);</span>         <span class="comment">// fails (as 'A' != 'B')</span>

<span class="identifier">test_generator_attr</span><span class="special">(</span><span class="string">"A"</span><span class="special">,</span> <span class="identifier">char_</span><span class="special">(</span><span class="char">'A'</span><span class="special">,</span> <span class="char">'Z'</span><span class="special">),</span> <span class="char">'A'</span><span class="special">);</span>
<span class="identifier">test_generator_attr</span><span class="special">(</span><span class="string">""</span><span class="special">,</span> <span class="identifier">char_</span><span class="special">(</span><span class="char">'A'</span><span class="special">,</span> <span class="char">'Z'</span><span class="special">),</span> <span class="char">'a'</span><span class="special">);</span>    <span class="comment">// fails (as 'a' does not belong to 'A'...'Z')</span>

<span class="identifier">test_generator_attr</span><span class="special">(</span><span class="string">"k"</span><span class="special">,</span> <span class="identifier">char_</span><span class="special">(</span><span class="string">"a-z0-9"</span><span class="special">),</span> <span class="char">'k'</span><span class="special">);</span>
<span class="identifier">test_generator_attr</span><span class="special">(</span><span class="string">""</span><span class="special">,</span> <span class="identifier">char_</span><span class="special">(</span><span class="string">"a-z0-9"</span><span class="special">),</span> <span class="char">'A'</span><span class="special">);</span>    <span class="comment">// fails (as 'A' does not belong to "a-z0-9")</span>
</pre>
<p>
          </p>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2001-2011 Joel de Guzman, Hartmut Kaiser<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="../char.html"><img src="../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../char.html"><img src="../../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="char_class.html"><img src="../../../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
